<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<!-- $Id: package.html,v 1.3 2005/08/12 02:56:51 dsyrstad Exp $
     Copyright (c) 2002, David A. Hall
-->
</head>
<body>

Provides Facade objects for working with the algorithm functors, and a variety
of utility iterators for various purposes.
<p>
The functionality that is adapted from STL is provided by a set of functors in
the net.sf.jga.fn.algorithm package operate on iterators.  To ease the 
transition to this approach, there are two facade objects whose methods 
correspond to the algorithms provided by STL.
<p>
The first, Algorithms, operates on collections, and is appropriate for getting 
easy answers to common questions over collections.  The second, Iterators, is 
closer conceptually to the implementation, and is more appropriate if the same
function is to be called several times for a given collection.  Most of the
methods in  these two facades are a single logical statement (although sometimes
the singe statement is broken up for formatting reasons) that constructs and
invokes the appropriate algorithm functor.
<p>
The summary of the functions adapted from STL is as follows:
<table>
  <tr><th>STL Function name</th><th>Facade method name</th><th>functor</th></tr>
  <tr><td><code>accumulate()</code></td><td>accumulate()</td><td>Accumulate</td></tr>
  <tr><td><code>adjacentDiff()</code></td><td>adjacentDiff()</td><td>TransformAdjacent(Minus)</td></tr>
  <tr><td><code>adjacent_find()</code></td><td>findAdjacent()</td><td>FindAdjacent</td></tr>
  <tr><td><code>count()</code></td><td>count()</td><td>Count</td></tr>
  <tr><td><code>count_if()</code></td><td>count()</td><td>Count</td></tr>
  <tr><td><code>equal()</code></td><td>equal()</td><td>varies based on form <sup>(3)</sup></td></tr>
  <tr><td><code>find()</code></td><td>find()</td><td>Find</td></tr>
  <tr><td><code>find_first_of()</code></td><td>findElement()</td><td>FindElement</td></tr>
  <tr><td><code>find_if()</code></td><td>find()</td><td>Find</td></tr>
  <tr><td><code>for_each()</code></td><td>forEach()</td><td>ForEach <sup>(2)</sup></td></tr>
  <tr><td><code>lexicographical_compare()</code></td><td>lessThan()</td><td>varies based on form <sup>(3)</sup></td></tr>
  <tr><td><code>max()</code></td><td>maximum()</td><td>Find,MaxValue <sup>(4)</sup></td></tr>
  <tr><td><code>max_element()</code></td><td>maximumValue()</td><td>MaxValue [collection]<br>Accumulate [iteration]</td></tr>
  <tr><td><code>merge()</code></td><td>merge()</td><td>Merge</td></tr>
  <tr><td><code>min()</code></td><td>minimum()</td><td>Find,MinValue <sup>(4)</sup></td></tr>
  <tr><td><code>min_element()</code></td><td>minimumValue()</td><td>MaxValue [collection]<br>Accumulate [iteration]</td></tr>
  <tr><td><code>mismatch()</code></td><td>mismatch()</td><td>FindMismatch</td></tr>
  <tr><td><code>remove()</code></td><td>removeAll</td><td>n/a<sup>(5)</sup></td></tr>
  <tr><td><code>remove_if()</code></td><td>removeAll</td><td>RemoveAll</td></tr>
  <tr><td><code>remove_copy()</code></td><td>removeAllCopy</td><td>RemoveAll<sup>(6)</sup></td></tr>
  <tr><td><code>remove_copy_if()</code></td><td>removeAllCopy</td><td>RemoveAll<sup>(6)</sup></td></tr>
  <tr><td><code>replace()</code></td><td>replaceAll</td><td>n/a<sup>(5)</sup></td></tr>
  <tr><td><code>replace_if()</code></td><td>replaceAll</td><td>ReplaceAll</td></tr>
  <tr><td><code>replace_copy()</code></td><td>replaceAllCopy</td><td>ReplaceAll<sup>(6)</sup></td></tr>
  <tr><td><code>replace_copy_if()</code></td><td>replaceAllCopy</td><td>ReplaceAll<sup>(6)</sup></td></tr>
  <tr><td><code>search()</code></td><td>match()</td><td>FindSequence</td></tr>
  <tr><td><code>search_n()</code></td><td>findRepeated()</td><td>FindRepeated</td></tr>
  <tr><td><code>transform</code> (unary form)</td><td>transformCopy</td><td>TransformUnary</td></tr>
  <tr><td><code>transform</code> (binary form)</td><td>transformCopy</td><td>TransformUnary</td></tr>
  <tr><td><code>unique()</code></td><td>unique</td><td>n/a<sup>(5)</sup></td></tr>
  <tr><td><code>unique_copy()</code></td><td>uniqueCopy</td><td>Unique<sup>(6)</sup></td></tr>
<!--  <tr><td><code>find_end()</code></td><td>n/a <sup>(1)</sup></td><td>n/a <sup>1</sup></td></tr> -->

</table>
<sup>(2)</sup> - The ForEach functor returns the result of the final call to the
given functor, where the method returns the given functor.<br>
<sup>(3)</sup> - The comparison operations are not implemented in terms of 
functors found in net.sf.jga.fn.algorithm: they are generally implemented via 
Comparators defined in net.sf.jga.util and comparison functors from 
net.sf.jga.fn.comparison.<br>
<sup>(4)</sup> - Only supported for collections, not for iterations.  Again, we'd
need to be able to clone iterators in order to support them.<br>
<sup>(5)</sup> - Works with Lists only (not general Collections).  The only option
available for updating in place is via a ListIterator.<br>
<sup>(6)</sup> - Unlike C++, the X_copy forms append to the output collection,
instead of overwriting it.  In C++, the implementations can't assume the right to
enlarge the output collection (it might be an array or some other fixed size
structure) while in Java, the collections aren't inherently fixed size (if the 
user passes a fixed size or capped size collection to one of these methods, we'll
pass through the appropriate exception, if necessary)
</body>
</html>
